home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d10 / pcippk.arc / SMTP.DOC < prev    next >
Encoding:
Text File  |  1990-03-29  |  8.4 KB  |  185 lines
  1.  
  2. 1. Synopsis
  3. include <nsmtp.h>               /* must include TCP, Timers before this */
  4.  
  5. 2. smtp open()
  6. Smtp smtp_ open(uc_ procs, mode [, for_ host])
  7.         int (*uc_ procs[6])();
  8.         int mode;               /* USER, SERVER, or REJECTION */
  9.         in_ name *for_ host;
  10.   This  routine  creates  an SMTP with six upcall procedures (explained later).
  11. The type of SMTP is controlled by the mode variable, which is set to the  USER,
  12. SERVER, or REJECTION constant.
  13.  
  14.   A  user  SMTP  sends  mail, and requires a third argument which specifies the
  15. foreign host for the TCP connection.  SMTP automatically picks a  random  local
  16. socket.
  17.  
  18.   Servers, which wait for connection from other hosts, receive mail.  To create
  19. a server, only the upcall procedures and the server type are needed.
  20.  
  21.   A Rejection SMTP is a special kind of  server  that  immediately  closes  the
  22. communication  channel  when  a  foreign hosts calls.  This type of SMTP can be
  23. used once the number of connected servers reaches a defined  limit  (like  when
  24. memory runs out).  Most foreign hosts will try to resend the mail later.
  25.  
  26. 3. User and Server Upcalls
  27.  
  28.  
  29.  
  30. 3.1. The Message Destination
  31. int us_ mail_ hop(smtp,from,to,host)            /* server mode only */
  32.         Smtp smtp;
  33.         char *from;  /* e.g. "<@comet,@mit-multics:DClark@mit-multics>" */
  34.         char *to;    /* e.g. "<gillies@mit-comet>"                      */
  35.         char *host;  /* e.g. "mit-comet"                                */
  36.   This  procedure communicates a mailbox path to the client.  The path contains
  37. an RFC822 "From:" and "To:" argument, and the next host to send  the  mail  to,
  38. each  terminated by a '\0'.  NOTE: The From: and To: lines are preprocessed: if
  39. the message is source-routed, one source host has already been  extracted  from
  40. the "To:" line and prepended to the "From:" line.
  41.  
  42.   The  strings  live in temporary storage so they should be immediately copied.
  43. If the SMTP server cannot accept the mail (i.e. if a local recipient  does  not
  44. exist),  SMTP  will  refuse  the  mail if us mail returns FALSE.  To accept the
  45. mail, it returns TRUE.  The text of the mail will be upcalled later.
  46.  
  47.  
  48.  
  49. 3.2. Major Smtp Events
  50. int us_ event(smtp,type)     /* server mode except open, close: both modes */
  51.         Smtp smtp;
  52.         int type;           /* OPEN, CLOSE, TURN, or RESET */
  53.   The OPEN event is upcalled when SMTP is open and ready  to  receive  or  send
  54. commands  to  the user.  When a connection turns around, the OPEN event will be
  55. upcalled once SMTP is ready for more input or output.  It is  illegal  to  make
  56. downcalls before each OPEN upcall.
  57.  
  58.   The  CLOSE  event  is  upcalled  when the communication channel is completely
  59. closed, and  the  connection  block  nears  deletion.    All  transactions  are
  60. acknowleged before the CLOSE event is upcalled.
  61.  
  62.   The  TURN  event upcall signals a request from SMTP to switch user and server
  63. roles.  A mail repository's SERVER might receive a  TURN  request,  from  other
  64. hosts  polling  the  repository for mail.  If the upcalled program can handle a
  65. TURN command, it should return TRUE, otherwise it should return FALSE.
  66.  
  67.   The RESET upcall invalidates any mail hop  and  us  data  upcalls  that  have
  68. already occured since the last us confirm upcall.
  69.  
  70.  
  71.  
  72. 3.3. Receiving the Mail Text
  73. us_ data(smtp,datablk)           /* server mode only */
  74.         Smtp smtp;
  75.         char *datablk;          /* A maximum of 1000 characters at once */
  76.   This  upcall  communicates a chunk of mail text to the client.  When the mail
  77. text ends, the us confirm() upcall confirms that the piece  of  mail  has  been
  78. reliably stored.
  79.  
  80.  
  81.  
  82. 3.4. Verifying the Mail is Stored
  83. int us_ confirm(smtp)            /* server mode only */
  84.         Smtp smtp;
  85.   This  upcall  terminates  a mail text (communicated by us data() upcalls) and
  86. ensures the text is reliably stored, before SMTP takes responsibility  for  the
  87. mail.   If for some reason the mail is not stored, the upcalled function should
  88. return FALSE.
  89.  
  90.  
  91.  
  92. 3.5. The Host's Name
  93. char *us_ get_ myname(smtp)       /* user and server smtp */
  94.         Smtp smtp;
  95.   This procedure must return the name of this host.  In some  cases,  one  host
  96. may  want  to dynamically masquerade as another (e.g. special mail forwarders).
  97. In these cases, the returned name can  be  computed  depending  on  lower-level
  98. information.    Normally  this  procedure  will return a constant pointer, like
  99. "MIT-ZUD".
  100.  
  101.  
  102.  
  103. 3.6. Result of a Mailing
  104. us_ sent(trans,status)           /* user smtp only */
  105.         SmtpTrans trans;        /* mail transaction */
  106.         int status              /* result of the transaction */
  107.   This procedure notifies the user about  whether  a  mailing  was  successful.
  108. There  are  at  least  5 reply codes:  NO FILE, ERROR, TRY LATER, NO SUCH USER,
  109. HOST PROBLEM, and SUCCESSFUL.  NO FILE is returned when the file to  be  mailed
  110. is  not  on  the disk.  ERROR indicates that there was an error in the from: or
  111. to: lines.  TRY LATER indicates that a temporary problem stopped the mail  from
  112. being  sent.  NO SUCH USER indicates that there was no such user on the foreign
  113. machine.  HOST PROBLEM  indicates  a  permanent  processing  problem  with  the
  114. foreign  SMTP  which  prevents it from receiving the mail.  Finally, SUCCESSFUL
  115. indicates that the mail has been reliably sent, and may be  deleted  from  this
  116. machine.
  117.  
  118. 4. User Mode SMTP
  119.  
  120.  
  121.  
  122. 4.1. smtp mail()
  123. SmtpTrans smtp_mail(smtp,from,to,message);
  124.         Smtp smtp;
  125.         char *from;             /* e.g. "<gillies@mit-comet>"    */
  126.         char *to;               /* e.g. "<romkey@borax>"         */
  127.         char *message;          /* the name of a message file     */
  128.   This  procedure  is  called to package a mail transaction.  Mail transactions
  129. are passed down to  SMTP  for  mailing,  and  acknowleged  by  upcalls.    Mail
  130. transactions  may be combined by SMTP for efficient transmission, especially if
  131. one file is being sent to many recipients on one  host.    SMTP  will  transmit
  132. these  efficiently  if the all the transactions fit into memory before they are
  133. flushed.
  134.  
  135.   These macros allow the user to decode a transaction
  136. char *Trans_ get_ from(x);      /* returns from: argument         */
  137. char *Trans_ get_ to(x);        /* returns to: argument           */
  138. char *Trans_ get_ filename(x);  /* returns the message file name  */
  139.  
  140.  
  141.  
  142. 4.2. smtp flush()
  143. smtp_ flush(smtp)
  144.         Smtp smtp;
  145.   This call forces Smtp to send any  outstanding  mail  transactions.    It  is
  146. especially  useful if the user program runs out of memory and must flush memory
  147. to free up space for new transactions.
  148.  
  149.  
  150.  
  151. 4.3. smtp close()
  152. smtp_ close(smtp)
  153.         Smtp smtp;
  154.   This procedure flushes all the mail transactions and closes the smtp channel.
  155. All  outstanding  mail transactions will soon be upcalled, and the the us event
  156. function will signal an SMTP close.
  157.  
  158.  
  159.  
  160. 4.4. smtp turn()
  161. int smtp_ turn(smtp)
  162.         Smtp smtp;
  163.   This procedure flushes  all  outstanding  mail  transactions,  and  asks  the
  164. foreign  host  to reverse server and user roles.  The procedure returns TRUE if
  165. the channel was turned around, or FALSE if the  foreign  host  refused.    This
  166. command allows one host to poll another for its mail.
  167.  
  168.  
  169.  
  170.                                Table of Contents
  171.    1. Synopsis                                                                0
  172.    2. smtp open()                                                             0
  173.    3. User and Server Upcalls                                                 0
  174.        3.1. The Message Destination                                           0
  175.        3.2. Major Smtp Events                                                 0
  176.        3.3. Receiving the Mail Text                                           0
  177.        3.4. Verifying the Mail is Stored                                      0
  178.        3.5. The Host's Name                                                   0
  179.        3.6. Result of a Mailing                                               0
  180.    4. User Mode SMTP                                                          0
  181.        4.1. smtp mail()                                                       0
  182.        4.2. smtp flush()                                                      0
  183.        4.3. smtp close()                                                      0
  184.        4.4. smtp turn()                                                       0
  185.